Configuring SequeLink^® Security for z/OS

This section describes how to configure SequeLink authentication, authorization, and data store logon, and how to activate terminal security for z/OS. The security of the SequeLink Server for z/OS is integrated with the z/OS security system using the SAF interface.

Configuring Authentication

On z/OS, SequeLink supports Kerberos, in addition to the anonymous and user ID and password authentication mechanisms:

For the user ID and password authentication mechanism, the client application must provide a valid user ID and password for the platform on which the SequeLink Server is running. The server verifies the user ID and password with the security package installed on z/OS. If verified, the server accepts the user ID as the identity of the client. When a password change is required (for example, when a password expires), the client application must also provide a new password.
For anonymous authentication, a UID map with a generic entry is needed. See "Using UID Mapping" for more information.
For Kerberos authentication, the SequeLink service principal name is retrieved from the Kerberos segment of the SequeLink Server user ID defined in your security manager, for example, RACF.

Configuring Authentication for Data Access Activities on z/OS

To configure authentication for data access activities, set the ServiceAuthMethods attribute to anonymous or OSLogon:

ServiceAuthMethods=anonymous 

or

ServiceAuthMethods=OSLogon(UID,PWD,NPWD) 

Configuring Authentication for Administrative Activities on z/OS

To configure authentication of administrative activities, set the ServiceAdminAuthMethods attribute to the following values:

ServiceAdminAuthMethods=OSLogon(UID,PWD) 

Configuring Authorization

To configure resource-based authorization for z/OS, enable the authorization setting for your service. You can also specify a security class and a security resource within this security class.

How you configure authorization depends on whether you are configuring it for data access activities, administrative activities, or enabling RACF resource security for a server data source.

Configuring Authorization for Data Access Activities at the Service or Data Source Level

To configure resource-based authorization for z/OS, set either MVSServiceAuthorizationEnable or MVSDataSourceAuthorizationEnable to True. The SequeLink Server validates the SequeLink Client's identity using the client's user ID and password and the client's authority to access the service or data source. If one of these options is used, you may specify a security resource and a security class. Also, any user that requires access to this SequeLink service or data source must be granted READ access to the specified resource defined in this class.

To configure resource-based authorization for data access activities, set the following attributes to the following values:

MVSServiceAuthorizationEnable=True for authorization on the service level or MVSDataSourceAuthorizationEnable=True for authorization on the data source level
MVSServiceAuthorizationClass=sec_class_name, where sec_class_name is the name of the security class where the MVSServiceAuthorizationResource is defined. The default value is FACILITY.
MVSServiceAuthorizationResource=sec_resource_name, where sec_resource_name is the name of the security resource where access is defined for your users. The default value is the name of the SequeLink data access service.

For data source authorization, the data source name is appended to the name of the security resource, for example, sec_resource_name.data_source_name.

Configuring Authorization for Administrative Activities

To configure resource-based authorization for administrative activities on z/OS, set MVSServiceAdminAuthorizationEnable to True. The SequeLink Server validates the SequeLink Client's identity using the client's user ID and password, and the client's authority to access the service. If this option is used, you also may specify a security resource and security class. Also, any user that requires access to this SequeLink service must be granted READ access to the specified resource defined in this class.

To configure resource-based authorization for administrative activities, set the following attributes to the following values:

Set MVSServiceAdminAuthorizationEnable to TRUE.
MVSServiceAdminAuthorizationResource=server_name, where server_name is the name of the SequeLink Server, or, on z/OS, the service name of the SequeLink agent.
MVSServiceAdminAuthorizationClass=sec_class_name, where sec_class_name is the name of the security class where the MVSServiceAdminAuthorizationResource is defined. The default value is FACILITY.

Configuring Data Store Logon

To allow the DBMS to inherit the operating system (or network) user identification to use for database authorization, set the DataSourceLogonMethod attribute to the following value:

DataSourceLogonMethod=OSIntegrated 

Activating Terminal Security

When terminal security is enabled and the RACF TERMINAL security class is activated, SequeLink Server verifies that the TCP/IP address (terminal ID) requesting the connection has permission to connect to the SequeLink Server. Even when the TERMINAL security class is not activated, a RACF (or equivalent) message informs you of the TCP/IP address of each user or application requesting a connection to the SequeLink Server.

Each TCP/IP address originating the client connection to SequeLink Server has an equivalent terminal ID used by the SAF security interface. SequeLink encodes each part of a TCP/IP address into its hexadecimal equivalent, and then, concatenates the four groups of two hexadecimal digits. For example, the TCP/IP address 10.131.40.59 would use the terminal ID 0A83283B as shown in the following example:

RDEFINE TERMINAL(0A83283B) UACC(NONE) 
PERMIT ZORGR CLASS TERMINAL ID(0A83283B) ACCESS(READ)  

An asterisk (*) can be used as a wildcard in a terminal ID to specify a range of TCP/IP addresses associated with a specific network. For example:

RDEFINE TERMINAL(0A8328*)  UACC(NONE) 
PERMIT GROP1 CLASS TERMINAL ID( 0A8328*)  ACCESS(READ) 

allows all users from group GROP1 to use the 10.131.40.xx network when connecting to the SequeLink Server. Any other users connecting from this network are denied access.

Before activating the RACF TERMINAL class:

Review the information on terminal security in your Security Manager documentation.
Remember that other applications, such as TSO, use the RACF TERMINAL class.
Define several terminals that have access to TSO to avoid creating a situation in which no one can log on.

The following examples show how to configure terminal security for SequeLink. Example A shows how to restrict specific TCP/IP addresses to specific users; example B shows how to restrict groups of users to specific TCP/IP addresses.

Prerequisite tasks for the following examples include:

Create the RACF GROUP named ZORGR with option NOTERMUACC.
Create the RACF userid ZORRO, making sure that the group ZORGR is the default group.
Connect user ZORRO to ZORGR.

Example A: Restricting TCP/IP Addresses to Specific Users

Grant read access to all terminals by setting UACC(READ). This ensures that no one can log on to TSO when you activate the TERMINAL class. For example:

SETROPTS TERMINAL(READ)

Set the terminal address so that it is not generally accessible. For example, to limit access to Terminal 0A83283B = TCPIP address 10.131.40.59:

RDEFINE TERMINAL(0A83283B) UACC(NONE)

PERMIT ZORGR CLASS TERMINAL ID(0A83283B) ACCESS(READ)

Group ZORGR users are allowed to access System from Terminal 0A83283B = TCPIP address 10.131.40.59.

Activate the TERMINAL class and load it in storage.

SETROPTS CLASSACT(TERMINAL) RACLIST(TERMINAL)

Example B: Restricting Groups of Users to Specific TCP/IP Addresses

This example shows how to restrict groups of users to specific TCP/IP addresses. For example, you may want to make sure that a user ID associated with an application running on an application server, such as IBM WebSphere, can only log on the SequeLink Server from a specific TCP/IP address.

Ensure that the NOTERMUACC option, which enforces UACC(NONE) on the TERMINAL class, is in effect for the Group WEBSPHR, even if you specified SETROPS TERMINAL(READ). Ensure that this is the default and only group.

ALTGROUP WEBSPHR NOTERMUACC

Grant UACC(READ) for all terminals to avoid a situation in which no one can log on to TSO once you activate the TERMINAL class. This will not apply to group WEBSPHR because of the NOTERMUACC option.

SETROPTS TERMINAL(READ)

RDEFINE TERMINAL(0A83283B) UACC(NONE)

Define Terminal 0A83283B = TCPIP address 10.131.40.59 as not accessible.

PERMIT WEBSHPR CLASS TERMINAL ID(0A83283B) ACCESS(READ)

Group WEBSHPR users are allowed to access the system from Terminal 0A83283B = TCPIP address 10.131.40.59, in combination with the NOTERMUACC option on GROUP WEBSPHR. This effectively restricts users of this Group to Terminal 10.131.40.59.

Activate class TERMINAL and load it in storage.

SETROPTS CLASSACT(TERMINAL) RACLIST(TERMINAL)

SequeLink^® Manager Security Attribute Defaults for z/OS

This section lists the installation defaults for SequeLink's security attributes for z/OS and describes the effect each combination of settings has on security.

Authentication Defaults for Administrative Activities

ServiceAdminAuthMethods=OSLogon(UID,PWD) 

The default for this attribute means that everyone who can provide a valid host user name and password will be allowed to administer and monitor the SequeLink Server.

Authentication Defaults for Data Access Activities

ServiceAuthMethods=OSLogon(UID,PWD) 
DataSourceLogonMethod=OSIntegrated 
DataSourceReadOnly=No 

The combination of defaults for these attributes means that everyone who can provide a valid host user name and password will be allowed to access the database using this service. The database connection accepts all types of SQL statements. Once connected to the database, the database security system will guarantee that the user can only perform actions that are allowed by the database administrator.

ServiceEncryptionAlgorithm=none 

The default for this attribute means that cleartext messages are transmitted between the client and server. Note that user IDs and passwords are never sent as cleartext.

Authorization Defaults

By default, authorization is disabled for administrative activities and data access.

Using UID Mapping

UID mapping is the mapping of user IDs to alternate user IDs using a UID map. You can use UID mapping to prevent users from updating DB2 tables using commonly available tools, such as QMF or SPUFI, while preserving their ability to update DB2 tables using SequeLink. For example, suppose a user, SMITH, has privileges defined in a UID map as shown:

User ID	DB2 Table Privilege	SequeLink Plan Privilege	Application
SMITH	UPDATE	EXECUTE	SequeLink service
SMITH	UPDATE	EXECUTE	SPUFI

In this example, SMITH can update DB2 tables using SPUFI and the SequeLink service.

To prevent SMITH from updating DB2 tables using SPUFI, you can map the logon ID to an alternate user ID (for example, SMITH=SMITHB). Once the logon ID SMITH has been mapped to the alternate user ID SMITHB, you can specify DB2 table privileges as shown:

User ID	DB2 Table Privilege	SequeLink Plan Privilege	Application
SMITHB	UPDATE	EXECUTE	SequeLink service
SMITH	SELECT	EXECUTE	SPUFI

The UPDATE privilege set for SMITHB allows SMITH to update DB2 tables using a SequeLink service. The SELECT privilege set for SMITH allows read-only access to the DB2 tables using SPUFI.

NOTE: Alternate UIDs are used internally for UID mapping only. If a SequeLink Client attempts to log on with an alternate UID, the logon will be rejected. You can also map an RACF group to a single alternate user, simplifying the administrative task of managing multiple users.

You can define multiple UID maps for the SequeLink Server. These maps can be referenced by the SequeLink server data sources; only one map can be referenced by the SequeLink service. The UID map defined at the SequeLink server data source takes precedence over the UID map defined at the SequeLink service level.

When a UID map is specified for a service or data source, the SequeLink Client's user ID is mapped to an alternate UID as specified in the UID map. If a UID map has been specified for the SequeLink service or data source, the alternate UID in the UID map will be used as the DB2 authorization ID when logging on to DB2. If an alternate UID cannot be found in the UID map, the SequeLink Client's logon ID will be used as the DB2 authorization ID when MVSUIDDefaultAccess=PERMIT. All status displays will continue to show the SequeLink Client's logon ID.

To configure UID mapping for a SequeLink service or data source, set the following attributes:

MVSDataSourceUIDMap	Specify the name of the UID map you want the data source to use.
MVSServiceUIDMap	Specify the name of the UID map you want the service to use.
MVSUIDDefaultAccess	Controls UID mapping behavior for a service or data source. Valid values include: PERMIT=If user ID mapping is set for the service or data source and the user ID cannot be found in the UID map, the connection is accepted. DENY=If user ID mapping is set for the service or data source and the user ID cannot be found in the UID map, the connection is refused.

To configure UID map entries, set the following attribute:

MVSUID

Specify an entry in the UID map using the format user=mapped_user or *=mapped_user, where: user is a valid user or user group for the z/OS security system. * is a wildcard for any user. mapped_user is a valid DB2 authorization ID. *=mapped_user is required when the service attributes ServiceAuthMethods=Anonymous and MVSServiceSecurity=SAFNONE.

For example, suppose you wanted to configure UID maps for a service and several data sources. First, you define the UID maps that the SequeLink service and the server data sources will use, as shown in Table 13-2:

Table 13-2. Defining UID Maps

UIDMap	UID	UID Map Definitions
UIDMap1	MVSUID MVSUID MVSUIDDefaultAccess	SMITH=SMITHA ERICK=ERICKA DENY
UIDMap2	MVSUID MVSUID MVSUID MVSUIDDefaultAccess	SMITH=APPDBA EDWARD=APPDBA *=APPDBU Permit

Then, you configure service SLDB2 with one of the UID maps defined in Table 13-2, specifying MVSServiceUIDMap=UIDMap1.

Finally, you configure data sources, both with and without UID maps, as shown in Table 13-3:

Table 13-3. SequeLink Data Source Definitions

Data Source	UID Service Settings
Accounting	MVSDataSourceUIDMap=UIDMap2
Shipping	No UID map was specified for this SequeLink server data source.

Using this example, the following scenarios could occur:

User ID	Service	Map ID	Action	Explanation
ALBERT	SLDB2A	n/a	Denied	Connection denied because ALBERT was not in UIDMAP1
ALBERT	SLDB2C	n/a	Permit	Connection permitted to SLDB2C as ALBERT
SMITH	SLDB2B	APPDB2B	Connect	Connection to SLDB2B as APPDB2B
EDWARDS	SLDB2B	APPDB2B	Connect	Connection to SLDB2B as APPDB2B
ERICK	SLDB2B	n/a	Denied	Connection denied because ERICK was not in UIDMAP2
ERICK	SLDB2C	ERICKC	Connect	Connection to SLDB2C as ERICKC
SMITH	SLDB2D	n/a	Connect	No UID mapping for SLDB2D
Anonymous	SLDB2B	n/a	Denied	Connection denied because no *=mapped_user entry in UID map
Anonymous	SLDB2E	APPDDB2Z	Connect	Connection to SLDB2E as APPDB2Z

Table 13-4 show several sample scenarios that could occur using the mappings in the preceding tables. In each case, the data source UIDMap, when present, takes precedence over the UIDMap of the service.

Table 13-4. Sample UID Mapping Scenarios 

User ID	Data Source	Map ID	Action and Explanation
ALBERT	Accounting	UIDMap2	Connection is permitted because ALBERT falls under the default access (PERMIT); the user ID is mapped to APPDB2U.
ALBERT	Shipping	UIDMap1	Connection to Shipping is refused because ALBERT is not named in UIDMap1, and the default access is set to DENY.
ERICK	Accounting	UIDMap2	Connection is permitted because ERICK falls under the default access (PERMIT); the user ID is mapped to APPDB2U.
ERICK	Shipping	UIDMap1	Connection is permitted because ERICK is an entry in UIDMap1; the user ID is mapped to ERICKA.
EDWARD	Accounting	UIDMap2	Connection is permitted because EDWARD is an entry in UIDMap2; the user ID is mapped to APPDBA.
EDWARD	Shipping	UIDMap1	Connection to Shipping is refused because EDWARD is not named in UIDMap1, and the default access is set to DENY.

Using Application IDs to Restrict User Access

Application IDs are alphanumeric strings passed by a SequeLink Client that identify the client application to a SequeLink service that has been configured to accept connections only from specific application IDs.

Application IDs add another layer of security for the connection to the data store beyond that provided by the Data Store Logon security mechanism. Data Store Logon allows all users of client applications to access the data store if they meet the qualifications set by Data Store Logon. Using application IDs, you can restrict connections to the data store to only those client applications that identify themselves to the SequeLink Server through an application ID.

On Windows platforms, application IDs can be specified explicitly by the client application or they can be automatically generated by the ODBC Client or the ADO Client. The advantage of using application IDs generated by the ODBC Client or ADO Client is the application itself does not need to contain the application ID; however, you must specify in the client application that you want to turn on the automatic generation of application IDs. The application ID is generated using the sha-1 hashing algorithm, resulting in a 160-bit hash value.

Specifying Application IDs Using ODBC Client Applications

This section describes how to specify application IDs explicitly using ODBC client applications and by turning on the automatic generation of application IDs.

Specifying Application IDs Explicitly

ODBC client applications can identify themselves explicitly to the SequeLink service in any of the following ways:

Specifying the application ID in the ODBC connection string that is passed to SQLDriverConnect. For example:

....;APPID=MyAppID;

or

....;ApplicationID=MyAppID;

where MyAppID is the application ID.

Specifying the application ID using SQLSetConnectAttr. Immediately after each call to SQLConnect or SQLDriverConnect connecting to the ODBC Client, call SQLSetConnectAttr as shown:

SQLSetConnectAttr(hdbc, 1053, "myAppId", SQL_NTS)

where myAppId is the application ID.

The SQLSetConnectAttr is defined in sql.h. If an incorrect application ID is specified, the SQLSetConnectAttr fails and all subsequent SQL statements fail.

Generating Application IDs Automatically

ODBC client applications can turn on automatic application ID generation in any of the following ways:

Specifying the automatic application ID method in the ODBC connection string that is passed to SQLDriverConnect. For example:

....;AutomaticApplicationID=x;

where x is set to one of the following values:

When set to 1, the full path of the application executable is used as input for the hash function.
When set to 2, the executable binary file is used as input for the hash function.
When set to 3, both the full path of the application executable and the executable binary file are used as input for the hash function.
When set to 4, the full directory name of the application executable is used as input for the hash function.
Specifying SQLSetConnectAttr. Immediately after each call to SQLConnect or SQLDriverConnect connecting to the ODBC Client, call SQLSetConnectAttr as shown:

SQLSetConnectAttr(hdbc, 1054, x, SQL_IS_INTEGER)

where x is one of the following values:

When set to 1, the full path of the application executable is used as input for the hash function.
When set to 2, the executable binary file is used as input for the hash function.
When set to 3, both the full path of the application executable and the executable binary file are used as input for the hash function.
When set to 4, the full directory name of the application executable is used as input for the hash function.

Specifying Application IDs Using ADO Client Applications

This section describes how to specify application IDs explicitly using ADO client applications and by turning on the automatic generation of application IDs.

Specifying Application IDs Explicitly

Using the ADO Client, the client application specifies the following key-value pair in the DBPROP_INIT_PROVIDERSTRING property of the DBPROPSET_DBINITALL property set:

ApplicationID=MyAppID;  

where myAppID is the application ID.

Generating Application IDs Automatically

Using the ADO Client, the client application specifies the following key-value pairs in the DBPROP_INIT_PROVIDERSTRING property of the DBPROPSET_DBINITALL property set:

Automatic Application ID=x 

where:

When Automatic Application ID is set to 1, the full path of the application executable is used as input for the hash function.
When Automatic Application ID is set to 2, the executable binary file is used as input for the hash function.
When Automatic Application ID is set to 3, both the full path of the application executable and the executable binary file are used as input for the hash function.
When Automatic Application ID is set to 4, the full directory name of the application executable is used as input for the hash function.

Specifying Application IDs Using JDBC Client Applications

After establishing a connection with the JDBC driver, immediately invoke setApplicationId. The setApplicationId method is defined on the interface com.ddtek.jdbc.extensions.SlExtensionInterface, and uses the following method prototype:

public void setApplicationId(String s) throws SQLException 

You can set the application ID as shown in the following example:

import java.sql.*; 
import com.ddtek.jdbc.extensions.SlExtensionInterface; 
... 
Connection con = DriverManager.getConnection(...); 
String appId = "myAppID";  
if (con instanceof SlExtensionInterface) 
   { 
   SlExtensionInterface slCon = (SlExtensionInterface)con; 
   slCon.setApplicationId(myAppID); 
   } 

where myAppID is the application ID.

Configuring the List of Authorized Application IDs

How you configure the list of authorized application IDs depends on whether the SequeLink Client specifies the application ID explicitly or allows the ODBC Client or ADO Client to automatically generate an application ID:

When the application explicitly specifies an application ID, set the DataSourceApplID service attribute to the application ID string.
When the application generates an automatic application ID (ODBC Clients and ADO Clients only), set the DataSourceAutoApplID service attribute to the value of the automatically generated application ID. Optionally, you can add a description of the attribute, for example:

DataSourceAutoAppId=InventoryControl=
aaf7798c8c66e6b3a6b7be6946

Continue to "Obtaining the Value of Automatically Generated Application IDs" for instructions on obtaining the value of automatically generated application IDs.

NOTE: The DataSourceApplID and DataSourceAutoApplID service attributes are not, by default, included in a data access service template; therefore, you must explicitly add them. See "Adding a Service Attribute" for instructions on adding service attributes.

Obtaining the Value of Automatically Generated Application IDs

Turn on the debug log level for the SequeLink service the client application will be using. For example, set ServiceDebugLogLevel=4 (Debug).
Connect to the SequeLink service with your ODBC or ADO application using the values 1, 2, 3, or 4 to turn on automatic application ID generation:
If 1 is specified, the full path of the application executable is used as input for the hash function.
If 2 is specified, the executable binary file is used as input for the hash function.
If 3 is specified, both the full path of the application executable and the executable binary file are used as input for the hash function.
If 4 is specified, the full directory name of the application executable is used as input for the hash function.

The connection request will fail and the following message will be generated:

[DataDirect][ODBC SequeLink driver][SequeLink Server]The application specified an invalid application identifier

Open the log file and look for the following entry:

CHAIN

      PROVIDE 
        refNum       :0 
        refNumType   :connect 
          direction  :set 
            000) Id  :kSSP PID CLOSEDID 
              Type   :binary 
              Info   :0xGAppID 
 

where the set of 40 characters following Info :0x is the generated application ID.

Configure the SequeLink service to accept the generated application ID by setting the DataSourceAutoApplID service attribute to the list of IDs you generated in Step 3.

NOTE: Remember to turn off the debug log level for the SequeLink service. (Set ServiceDebugLogLevel=3 (Error))

Configuring TCP/IP Location Filters

TCP/IP location filters allow you to control which clients have access to a SequeLink service based on the network address of the client originating the request. To configure TCP/IP location filters for:

A SequeLink data access service, set the ServiceAuthorizedClient service attribute.
A SequeLink agent service, set the ServiceAuthorizedAdminClient service attribute.

You can specify one or multiple location filters in either address or name formats as shown in the following examples:

Client TCP/IP host name	burner.ddtek.com
Client TCP/IP domain names (using a wildcard)	192.16.2.* or *.ddtek.com
Client TCP/IP address	127.0.0.1
Client TCP/IP address range (using a wildcard)	192.16.*.*

NOTE: When using host names, the ServiceResolveHostNames service attribute must be set to TRUE, and only primary domain names can be used.

To configure multiple TCP/IP location filters, you must set the ServiceAuthorizedClient or ServiceAuthorizedAdminClient attribute multiple times, one instance for each location filter. For example:

ServiceAuthorizedClient=192.16.*.* 
ServiceAuthorizedClient=192.17.*.* 
ServiceAuthorizedClient=192.18.*.*